Custom Messages
Custom Messages provide the ability to transmit collected sensor data in user defined formats over various outputs ranging from serial/network communication ports to files or emails. Custom Message widgets are similar to Events in that they are not utilized inside Layouts and instead have their own dedicated management page. The user defines the formatted message and data to be sent through a Custom Message widget and then runs them via the Custom Messaging page under the Data Management menu item.
Custom Messages are very useful to combine various sensor data items into a single data string which you can then send to other programs at a periodic interval. For instance, if a scientist has a tool which requires GPS, both Gyros and the current depth, you can create a Custom Message with all these components and send them to the tool every second over the network. In the past this feature of SCS has been critical for 3rd party software running on the ship to get data streams quickly and efficiently.
This feature is managed by the Data Dissemination Service running in the background.
As with all of SCS - no critical (Life or Limb) systems should rely on this feature. These type systems should be implemented per vendor guidance.
Designing the Widget
Click the Custom Messages link on the Manage My Widgets panel then click the +Create New Custom Message button on top of the grid.
Enter the standard information for widget creation including a name, description, any keywords and permission level you wish this template to have and hit OK.
This will bring you to the editor for this widget.
The editor is broken down into three main areas of concern,
- Building out the contents of the data you want to send
- How you want to package those contents
- How often and where you want to send the custom package
Message Definition
The Message Definition section is where you build out the contents of the data you want to send. It consists of a toolbar where you pick what you want to add to your message and then a grid showing you each component you have added and how it relates to the others (e.g. display order). You can change the order of items in the grid by drag-and-drop.
As you add components or change your packaging format a sample of your message will be displayed for your review at the bottom of the editor.
The toolbar consists of 4 main types of components you can add to your message.
Date / Time
The first is a Date / Time, if you want to add a timestamp to your outgoing message this is the option you should choose. SCS provides a large number of variations for formatting a date and or time, choose the one that is right for the receiving application.
As an alternative, you could use a timestamp data field from a sensor instead, such as a ZDA message, though you cannot customize their format.
SCS Timestamps are taken from the SCS server's local system clock (should be sync'd with the ship's time/NTP/PTP/AD) and by default is in UTC.
Though in no way required, it is recommended that the first value in your message be some sort of ID which uniquely identifies your package (use the Add Text component to do this). That can be immediately followed by the timestamp of the message. Take a look at the $GPGGA message as an example.
Sensor
The next component option is Sensor, this is where the majority of your message definition will come from. Clicking this allows you to add sensor data to your message, this can be a full RAW message definition or an individual data field. You will most likely click this button repeatedly to add multiple sensor data components to your message.
Clicking this will bring up the standard sensor selection UI, click the item you want to include in your message and hit OK.
If the sensor item you are adding is a data field and is in the Latitude or Longitude category (CFE) then you can also reformat it into various Lat/Lon formats (such as Decimal Degrees) on the fly prior to sending it out via this Custom Message.
Control Character
The Control Character component adds a control character (a hidden character which indicates something to the computer reading the message) to your definition. The two most common control characters (a line feed and a carriage return) are quickly available via the dropdown. A full list is available if you click the button itself.
In order for the receiving tool to know that it has received a full message it is advisable to have a control character at the end of your definition. Normally this would be a carriage return followed by a line feed. Work with anyone receiving (the person who requested this message) the data to determine what, if any, control characters they need and where they need them.
Most likely the only time you need to add control characters is if you choose Exact for your packing format. If you choose any format other than Exact chances are you can ignore control characters completely and not add them to your message at all as it is automatically taken care of for you.
Custom Text
The Add Text component allows you to enter hard coded custom strings into your message, such as a unique ID or custom sentence label at the beginning. If you were to choose the Exact packaging format then you might use this to add commas between each component. Essentially whatever you type here will show up in your message exactly as you typed it.
Packaging Format
The Packaging Format section is where you decide how you want SCS to combine all your message components prior to sending it out. There are a few options, talk with the owners of the receiving applications to figure out which works best for them.
Each option has a description as to how it would package your message. The most likely option is Comma Delimited, which injects a comma between each component in your message and automatically appends a carriage return and a line feed to the end for you.
For example, for the given component list below:
A Comma Delimted format results in a clean string
$DEMO_CM,2019-08-23 18:33:40Z,-Unknown-,-Unknown-,-Unknown- <cr><lf>
-Unknown- is injected when sensor data for the given component is not available (ACQ is off, sensor is off, etc)
But if changed to the Exact format then the commas are lost and no control characters are added for you
$DEMO_CM2019-08-23 18:39:06Z-Unknown--Unknown--Unknown-
To get the Exact format to work like the Comma Delimited you would have to manually add commas and control characters, turning the above definition into:
While the end result of the above examples are the same, the Exact format gives you much finer control. However, it is also much more verbose, harder to read and harder to maintain. For that reason it is recommended you only use the Exact format as a last resort.
Update Rate
The Update Rate allows you to specify how often you want your message sent out. It also has an option to have this message automatically started whenever the service is started (e.g. after the entire server is rebooted). In the example below the message is sent out once every second and will automatically start sending whenever the service comes online.
Custom Messages can also be automatically started/stopped via GIS Triggers.
Output Configuration
The Output Configuration section is where you define where you want your messages sent. Depending on which output type you select you will be presented with different options to further refine your target.
Serial Port
This output will push your data out a serial communications port located on the server itself. The settings you specify here will have to be matched to whatever is listening in on the other side of the serial line.
TCP/IP
This output will push your data out from the server via TCP. This is a good reliable communications protocol over a network, however the computer the client software / target is running on will have to be able to connect to the SCS server over the network. This may require you to open firewall or ACL holes in your network(s) depending on which VLAN the various systems are running in. In a client-server architecture SCS acts as the server in this instance and remote clients should connect directly to it on the port specified.
UDP/IP
This output will push your data out from the server via UDP. This is another protocol which sits on IP, it is not reliable but excels at broad announcements (broadcasts) and speed since it doesn't have all the overhead associated with TCP. However, as with TCP, it is a network based communications protocol and the computer the client software / target is running on will have to be able to connect to the SCS server over the network (or packets from the SCS server have to be able to reach the client machine). This may require you to open firewall or ACL holes in your network(s) depending on which VLAN the various systems are running in. Multi-cast might require further switch level modifications, consult with your network administrator for more information. In a client-server architecture SCS acts as the server in this instance and remote clients should listen for packets from it on the port specified.
SignalR
This output will push your data out from the server server via a SignalR hub. This is the same technology SCS uses throughout the website for most near real-time communication between all users and the backend services. There are various libraries written in python and other languages if users want to directly connect via SignalR and use it in their own applications.
The name of the Hub to connect to is "UserDefinedMessage"
File
This output will push your data out to a file directly on the filesystem.
If trying to write to a network drive you might want to use a FQDN and ensure the share has granted permissions to the account the Data Dissemination Service is running as. Be aware drive mappings are tied to a profile and have proven to be somewhat flaky in the past.
This output will send your data out via an email at every elapse of the Update Rate interval.
Having a low update rate could result in saturation of your email system. Be careful using this if you have a low update rate (e.g. if your update rate is 1 second then every second an email will go out with the message, which is 86,400 emails per day just for the single Custom Message!
Run Time
Custom Messages are run via the Custom Messaging page inside the Data Management main menu item.
Each template is displayed in a grid, the last column allows you to start or stop the message from going out.
